Майстерність роботи з файловою системою в TypeScript: Операції з файлами в Node.js з безпекою типів для глобальних розробників

У широкому ландшафті сучасної розробки програмного забезпечення Node.js виступає потужним середовищем виконання для створення масштабованих серверних додатків, інструментів командного рядка тощо. Фундаментальним аспектом багатьох додатків на Node.js є взаємодія з файловою системою – читання, запис, створення та керування файлами й каталогами. Хоча JavaScript надає гнучкість для виконання цих операцій, впровадження TypeScript підносить цей досвід на новий рівень, додаючи статичну перевірку типів, покращені інструменти та, зрештою, вищу надійність і зручність підтримки вашого коду для роботи з файловою системою.

Цей вичерпний посібник створений для глобальної аудиторії розробників, незалежно від їхнього культурного походження чи географічного розташування, які прагнуть опанувати операції з файлами в Node.js з надійністю, яку пропонує TypeScript. Ми заглибимося в основний модуль `fs`, розглянемо його різноманітні синхронні та асинхронні парадигми, вивчимо сучасні API на основі промісів і дізнаємося, як система типів TypeScript може значно зменшити кількість поширених помилок та покращити зрозумілість вашого коду.

Наріжний камінь: Розуміння файлової системи Node.js (`fs`)

Модуль `fs` у Node.js надає API для взаємодії з файловою системою, змодельований за стандартними функціями POSIX. Він пропонує широкий спектр методів, від базового читання та запису файлів до складних маніпуляцій з каталогами та спостереження за файлами. Традиційно ці операції оброблялися за допомогою колбеків, що призводило до сумнозвісного «пекла колбеків» у складних сценаріях. З розвитком Node.js проміси та `async/await` стали бажаними патернами для асинхронних операцій, роблячи код більш читабельним та керованим.

Чому варто використовувати TypeScript для операцій з файловою системою?

Хоча модуль `fs` у Node.js чудово працює зі звичайним JavaScript, інтеграція TypeScript надає кілька вагомих переваг:

• Безпека типів: Виявляє поширені помилки, як-от неправильні типи аргументів, відсутні параметри або неочікувані значення, що повертаються, ще на етапі компіляції, до запуску коду. Це безцінно, особливо при роботі з різними кодуваннями файлів, прапорцями та об'єктами `Buffer`.
• Покращена читабельність: Явні анотації типів чітко показують, які дані очікує функція і що вона поверне, покращуючи розуміння коду для розробників у різноманітних командах.
• Кращі інструменти та автодоповнення: IDE (наприклад, VS Code) використовують визначення типів TypeScript для надання інтелектуального автодоповнення, підказок щодо параметрів та вбудованої документації, що значно підвищує продуктивність.
• Впевненість при рефакторингу: Коли ви змінюєте інтерфейс або сигнатуру функції, TypeScript негайно позначає всі залежні місця, роблячи масштабний рефакторинг менш схильним до помилок.
• Глобальна послідовність: Забезпечує послідовний стиль кодування та розуміння структур даних у міжнародних командах розробників, зменшуючи неоднозначність.

Синхронні та асинхронні операції: Глобальна перспектива

Розуміння різниці між синхронними та асинхронними операціями є критично важливим, особливо при створенні додатків для глобального розгортання, де продуктивність та швидкість реагування є першочерговими. Більшість функцій модуля `fs` мають синхронні та асинхронні варіанти. Як правило, асинхронні методи є кращими для неблокуючих операцій вводу-виводу, що є необхідним для підтримки швидкості реагування вашого сервера Node.js.

• Асинхронні (неблокуючі): Ці методи приймають функцію зворотного виклику (колбек) як останній аргумент або повертають `Promise`. Вони ініціюють операцію з файловою системою і негайно повертають управління, дозволяючи виконуватися іншому коду. Коли операція завершується, викликається колбек (або проміс виконується/відхиляється). Це ідеально підходить для серверних додатків, що обробляють кілька одночасних запитів від користувачів з усього світу, оскільки це запобігає «зависанню» сервера в очікуванні завершення файлової операції.
• Синхронні (блокуючі): Ці методи виконують операцію повністю перед поверненням управління. Хоча їх простіше писати, вони блокують цикл подій Node.js, не дозволяючи виконуватися іншому коду до завершення операції з файловою системою. Це може призвести до значних вузьких місць у продуктивності та невідповідаючих додатків, особливо в середовищах з високим трафіком. Використовуйте їх зрідка, зазвичай для логіки запуску додатку або простих скриптів, де блокування є прийнятним.

Основні типи файлових операцій у TypeScript

Давайте заглибимося в практичне застосування TypeScript для поширених операцій з файловою системою. Ми будемо використовувати вбудовані визначення типів для Node.js, які зазвичай доступні через пакет `@types/node`.

Для початку переконайтеся, що у вашому проєкті встановлено TypeScript та типи Node.js:

npm install typescript @types/node --save-dev

Ваш `tsconfig.json` повинен бути налаштований відповідним чином, наприклад:

{ "compilerOptions": { "target": "es2020", "module": "commonjs", "outDir": "./dist", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true }, "include": ["src/**/*"] }

Читання файлів: `readFile`, `readFileSync` та Promises API

Читання вмісту з файлів є фундаментальною операцією. TypeScript допомагає переконатися, що ви правильно обробляєте шляхи до файлів, кодування та потенційні помилки.

Асинхронне читання файлу (на основі колбеків)

`fs.readFile` є основною функцією для асинхронного читання файлів. Вона приймає шлях, необов'язкове кодування та функцію зворотного виклику. TypeScript гарантує, що аргументи колбеку мають правильні типи (`Error | null`, `Buffer | string`).

import * as fs from 'fs'; const filePath: string = 'data/example.txt'; fs.readFile(filePath, 'utf8', (err: NodeJS.ErrnoException | null, data: string) => { if (err) { // Логуємо помилку для міжнародного налагодження, напр., 'Файл не знайдено' console.error(`Помилка читання файлу '${filePath}': ${err.message}`); return; } // Обробляємо вміст файлу, переконуючись, що це рядок згідно з кодуванням 'utf8' console.log(`Вміст файлу (${filePath}):\n${data}`); }); // Приклад: Читання бінарних даних (кодування не вказано) const binaryFilePath: string = 'data/image.png'; fs.readFile(binaryFilePath, (err: NodeJS.ErrnoException | null, data: Buffer) => { if (err) { console.error(`Помилка читання бінарного файлу '${binaryFilePath}': ${err.message}`); return; } // 'data' тут є буфером, готовим до подальшої обробки (напр., потокової передачі клієнту) console.log(`Прочитано ${data.byteLength} байт з ${binaryFilePath}`); });

Синхронне читання файлу

`fs.readFileSync` блокує цикл подій. Його тип повернення — `Buffer` або `string`, залежно від того, чи вказано кодування. TypeScript правильно виводить цей тип.

import * as fs from 'fs'; const syncFilePath: string = 'data/sync_example.txt'; try { const content: string = fs.readFileSync(syncFilePath, 'utf8'); console.log(`Вміст, прочитаний синхронно (${syncFilePath}):\n${content}`); } catch (error: any) { console.error(`Помилка синхронного читання для '${syncFilePath}': ${error.message}`); }

Читання файлу на основі промісів (`fs/promises`)

Сучасний API `fs/promises` пропонує чистіший інтерфейс на основі промісів, який наполегливо рекомендується для асинхронних операцій. TypeScript тут особливо корисний, особливо з `async/await`.

import * as fsPromises from 'fs/promises'; async function readTextFile(path: string): Promise { try { // fsPromises.readFile виводить тип повернення як string, якщо вказано 'utf8' const content: string = await fsPromises.readFile(path, { encoding: 'utf8' }); console.log(`Вміст, прочитаний на основі промісів (${path}):\n${content}`); } catch (error: any) { console.error(`Помилка читання на основі промісів для '${path}': ${error.message}`); } } async function readBinaryFile(path: string): Promise { try { // fsPromises.readFile виводить тип повернення як Buffer, якщо кодування не вказано const buffer: Buffer = await fsPromises.readFile(path); console.log(`Бінарний вміст, прочитаний на основі промісів (${path}): ${buffer.byteLength} байт`); } catch (error: any) { console.error(`Помилка читання бінарного файлу на основі промісів для '${path}': ${error.message}`); } } // Створюємо демонстраційні файли (необов'язково, для локального тестування) async function setupFiles() { await fsPromises.mkdir('data', { recursive: true }); await fsPromises.writeFile('data/example.txt', 'Привіт від TypeScript FS!'); await fsPromises.writeFile('data/sync_example.txt', 'Синхронний вміст.'); // Для бінарних даних просто створюємо невеликий буфер await fsPromises.writeFile('data/image.png', Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A])); } setupFiles().then(() => { readTextFile('data/example.txt'); readTextFile('non_existent_file.txt'); // Демонструє обробку помилок readBinaryFile('data/image.png'); }).catch(err => console.error('Помилка налаштування:', err));

Запис файлів: `writeFile`, `writeFileSync` та прапорці

Запис даних у файли є не менш важливим. TypeScript допомагає керувати шляхами до файлів, типами даних (рядок або Buffer), кодуванням та прапорцями відкриття файлів.

Асинхронний запис файлу

`fs.writeFile` використовується для запису даних у файл, замінюючи файл, якщо він уже існує за замовчуванням. Ви можете контролювати цю поведінку за допомогою `прапорців`.

import * as fs from 'fs'; const outputFilePath: string = 'data/output.txt'; const fileContent: string = 'Це новий вміст, записаний TypeScript.'; fs.writeFile(outputFilePath, fileContent, 'utf8', (err: NodeJS.ErrnoException | null) => { if (err) { console.error(`Помилка запису файлу '${outputFilePath}': ${err.message}`); return; } console.log(`Файл '${outputFilePath}' успішно записано.`); }); // Приклад з даними Buffer const bufferContent: Buffer = Buffer.from('Приклад бінарних даних'); const binaryOutputFilePath: string = 'data/binary_output.bin'; fs.writeFile(binaryOutputFilePath, bufferContent, (err: NodeJS.ErrnoException | null) => { if (err) { console.error(`Помилка запису бінарного файлу '${binaryOutputFilePath}': ${err.message}`); return; } console.log(`Бінарний файл '${binaryOutputFilePath}' успішно записано.`); });

Синхронний запис файлу

`fs.writeFileSync` блокує цикл подій до завершення операції запису.

import * as fs from 'fs'; const syncOutputFilePath: string = 'data/sync_output.txt'; try { fs.writeFileSync(syncOutputFilePath, 'Синхронно записаний вміст.', 'utf8'); console.log(`Файл '${syncOutputFilePath}' записано синхронно.`); } catch (error: any) { console.error(`Помилка синхронного запису для '${syncOutputFilePath}': ${error.message}`); }

Запис файлу на основі промісів (`fs/promises`)

Сучасний підхід з `async/await` та `fs/promises` часто є чистішим для керування асинхронними записами.

import * as fsPromises from 'fs/promises'; import { constants as fsConstants } from 'fs'; // Для прапорців async function writeDataToFile(path: string, data: string | Buffer): Promise { try { await fsPromises.writeFile(path, data, { encoding: 'utf8' }); console.log(`Файл '${path}' успішно записано за допомогою промісів.`); } catch (error: any) { console.error(`Помилка запису файлу '${path}' з промісами: ${error.message}`); } } // Демонстрація перезапису проти дозапису з використанням прапорців async function writeWithFlags(path: string, data: string, flag: string | number): Promise { try { await fsPromises.writeFile(path, data, { flag: flag, encoding: 'utf8' }); console.log(`Файл '${path}' успішно записано з прапорцем '${flag}'.`); } catch (error: any) { console.error(`Помилка запису файлу '${path}' з прапорцем '${flag}': ${error.message}`); } } (async () => { // Початковий запис (створює або перезаписує) await writeDataToFile('data/flags_example.txt', 'Перший рядок.\n'); // Дозапис до існуючого файлу await writeWithFlags('data/flags_example.txt', 'Другий рядок (дозаписано).\n', 'a'); // Запис, лише якщо файл не існує (ексклюзивний запис) await writeWithFlags('data/new_exclusive.txt', 'Ексклюзивний вміст.\n', 'wx'); // Ця операція зазнає невдачі, якщо 'data/new_exclusive.txt' вже існує з попереднього запуску await writeWithFlags('data/new_exclusive.txt', 'Спроба перезаписати ексклюзивний вміст (має завершитись невдачею, якщо файл існує).\n', 'wx'); })();

Важливі прапорці:

• `'w'` (за замовчуванням): Відкрити файл для запису. Файл створюється (якщо не існує) або обрізається (якщо існує).
• `'w+'`: Відкрити файл для читання та запису. Файл створюється (якщо не існує) або обрізається (якщо існує).
• `'a'` (дозапис): Відкрити файл для дозапису. Файл створюється, якщо не існує.
• `'a+'`: Відкрити файл для читання та дозапису. Файл створюється, якщо не існує.
• `'r'` (читання): Відкрити файл для читання. Виникає виняток, якщо файл не існує.
• `'r+'`: Відкрити файл для читання та запису. Виникає виняток, якщо файл не існує.
• `'wx'` (ексклюзивний запис): Подібно до `'w'`, але завершується невдачею, якщо шлях існує.
• `'ax'` (ексклюзивний дозапис): Подібно до `'a'`, але завершується невдачею, якщо шлях існує.

Дозапис у файли: `appendFile`, `appendFileSync`

Коли вам потрібно додати дані в кінець існуючого файлу, не перезаписуючи його вміст, ваш вибір — `appendFile`. Це особливо корисно для логування, збору даних або ведення аудиторських журналів.

Асинхронний дозапис

import * as fs from 'fs'; const logFilePath: string = 'data/app_logs.log'; function logMessage(message: string): void { const timestamp: string = new Date().toISOString(); const logEntry: string = `${timestamp} - ${message}\n`; fs.appendFile(logFilePath, logEntry, 'utf8', (err: NodeJS.ErrnoException | null) => { if (err) { console.error(`Помилка дозапису в лог-файл '${logFilePath}': ${err.message}`); return; } console.log(`Повідомлення залоговано в '${logFilePath}'.`); }); } logMessage('Користувач "Alice" увійшов у систему.'); setTimeout(() => logMessage('Ініційовано оновлення системи.'), 50); logMessage('З\'єднання з базою даних встановлено.');

Синхронний дозапис

import * as fs from 'fs'; const syncLogFilePath: string = 'data/sync_app_logs.log'; function logMessageSync(message: string): void { const timestamp: string = new Date().toISOString(); const logEntry: string = `${timestamp} - ${message}\n`; try { fs.appendFileSync(syncLogFilePath, logEntry, 'utf8'); console.log(`Повідомлення залоговано синхронно в '${syncLogFilePath}'.`); } catch (error: any) { console.error(`Синхронна помилка дозапису в лог-файл '${syncLogFilePath}': ${error.message}`); } } logMessageSync('Додаток запущено.'); logMessageSync('Конфігурацію завантажено.');

Дозапис на основі промісів (`fs/promises`)

import * as fsPromises from 'fs/promises'; const promiseLogFilePath: string = 'data/promise_app_logs.log'; async function logMessagePromise(message: string): Promise { const timestamp: string = new Date().toISOString(); const logEntry: string = `${timestamp} - ${message}\n`; try { await fsPromises.appendFile(promiseLogFilePath, logEntry, 'utf8'); console.log(`Повідомлення залоговано за допомогою промісів у '${promiseLogFilePath}'.`); } catch (error: any) { console.error(`Помилка дозапису в лог-файл '${promiseLogFilePath}' з промісами: ${error.message}`); } } (async () => { await logMessagePromise('Сервіс ініціалізовано.'); await logMessagePromise('Розпочато обробку даних.'); })();

Видалення файлів: `unlink`, `unlinkSync`

Видалення файлів з файлової системи. TypeScript допомагає переконатися, що ви передаєте правильний шлях та коректно обробляєте помилки.

Асинхронне видалення

import * as fs from 'fs'; const fileToDeletePath: string = 'data/temp_to_delete.txt'; // Спочатку створюємо файл, щоб він існував для демонстрації видалення fs.writeFile(fileToDeletePath, 'Тимчасовий вміст.', 'utf8', (err) => { if (err) { console.error('Помилка створення файлу для демонстрації видалення:', err); return; } console.log(`Файл '${fileToDeletePath}' створено для демонстрації видалення.`); fs.unlink(fileToDeletePath, (err: NodeJS.ErrnoException | null) => { if (err) { console.error(`Помилка видалення файлу '${fileToDeletePath}': ${err.message}`); return; } console.log(`Файл '${fileToDeletePath}' успішно видалено.`); }); });

Синхронне видалення

import * as fs from 'fs'; const syncFileToDeletePath: string = 'data/sync_temp_to_delete.txt'; try { fs.writeFileSync(syncFileToDeletePath, 'Синхронний тимчасовий вміст.', 'utf8'); console.log(`Файл '${syncFileToDeletePath}' створено.`); fs.unlinkSync(syncFileToDeletePath); console.log(`Файл '${syncFileToDeletePath}' видалено синхронно.`); } catch (error: any) { console.error(`Помилка синхронного видалення для '${syncFileToDeletePath}': ${error.message}`); }

Видалення на основі промісів (`fs/promises`)

import * as fsPromises from 'fs/promises'; const promiseFileToDeletePath: string = 'data/promise_temp_to_delete.txt'; async function deleteFile(path: string): Promise { try { // Спочатку створюємо файл для демонстраційних цілей await fsPromises.writeFile(path, 'Тимчасовий вміст промісу.', 'utf8'); console.log(`Файл '${path}' створено для демонстрації видалення з промісами.`); await fsPromises.unlink(path); console.log(`Файл '${path}' успішно видалено за допомогою промісів.`); } catch (error: any) { console.error(`Помилка видалення файлу '${path}' з промісами: ${error.message}`); } } deleteFile(promiseFileToDeletePath);

Перевірка існування файлу та дозволів: `existsSync`, `access`, `accessSync`

Перед виконанням операцій з файлом може знадобитися перевірити, чи він існує, або чи має поточний процес необхідні дозволи. TypeScript допомагає, надаючи типи для параметра `mode`.

Синхронна перевірка існування

`fs.existsSync` — це проста синхронна перевірка. Хоча вона зручна, вона має вразливість до стану гонитви (файл може бути видалений між `existsSync` та наступною операцією), тому для критичних операцій часто краще використовувати `fs.access`.

import * as fs from 'fs'; const checkFilePath: string = 'data/example.txt'; if (fs.existsSync(checkFilePath)) { console.log(`Файл '${checkFilePath}' існує.`); } else { console.log(`Файл '${checkFilePath}' не існує.`); }

Асинхронна перевірка дозволів (`fs.access`)

`fs.access` перевіряє дозволи користувача для файлу або каталогу, вказаного `path`. Вона асинхронна і приймає аргумент `mode` (наприклад, `fs.constants.F_OK` для існування, `R_OK` для читання, `W_OK` для запису, `X_OK` для виконання).

import * as fs from 'fs'; import { constants } from 'fs'; const accessFilePath: string = 'data/example.txt'; fs.access(accessFilePath, constants.F_OK, (err: NodeJS.ErrnoException | null) => { if (err) { console.error(`Файл '${accessFilePath}' не існує або доступ заборонено.`); return; } console.log(`Файл '${accessFilePath}' існує.`); }); fs.access(accessFilePath, constants.R_OK | constants.W_OK, (err: NodeJS.ErrnoException | null) => { if (err) { console.error(`Файл '${accessFilePath}' не доступний для читання/запису або доступ заборонено: ${err.message}`); return; } console.log(`Файл '${accessFilePath}' доступний для читання та запису.`); });

Перевірка дозволів на основі промісів (`fs/promises`)

import * as fsPromises from 'fs/promises'; import { constants } from 'fs'; async function checkFilePermissions(path: string, mode: number): Promise { try { await fsPromises.access(path, mode); const modeDescription = (mode === constants.F_OK ? 'існує' : '') + ((mode & constants.R_OK) ? ' для читання' : '') + ((mode & constants.W_OK) ? ' для запису' : '') + ((mode & constants.X_OK) ? ' для виконання' : ''); console.log(`Файл '${path}' доступний ${modeDescription.trim()}.`); } catch (error: any) { console.error(`Помилка доступу до файлу '${path}': ${error.message}`); } } (async () => { await checkFilePermissions('data/example.txt', constants.F_OK); // Перевірка існування await checkFilePermissions('data/example.txt', constants.R_OK | constants.W_OK); // Перевірка читання/запису await checkFilePermissions('data/non_existent_file.txt', constants.F_OK); // Має повернути помилку })();

Отримання інформації про файл: `stat`, `statSync`, `fs.Stats`

Сімейство функцій `fs.stat` надає детальну інформацію про файл або каталог, таку як розмір, дата створення, дата модифікації та дозволи. Інтерфейс `fs.Stats` у TypeScript робить роботу з цими даними структурованою та надійною.

Асинхронний stat

import * as fs from 'fs'; import { Stats } from 'fs'; const statFilePath: string = 'data/example.txt'; fs.stat(statFilePath, (err: NodeJS.ErrnoException | null, stats: Stats) => { if (err) { console.error(`Помилка отримання статистики для '${statFilePath}': ${err.message}`); return; } console.log(`Статистика для '${statFilePath}':`); console.log(` Це файл: ${stats.isFile()}`); console.log(` Це каталог: ${stats.isDirectory()}`); console.log(` Розмір: ${stats.size} байт`); console.log(` Час створення: ${stats.birthtime.toISOString()}`); console.log(` Остання модифікація: ${stats.mtime.toISOString()}`); });

Stat на основі промісів (`fs/promises`)

import * as fsPromises from 'fs/promises'; import { Stats } from 'fs'; // Все ще використовуємо інтерфейс Stats з модуля 'fs' async function getFileStats(path: string): Promise { try { const stats: Stats = await fsPromises.stat(path); console.log(`Статистика на основі промісів для '${path}':`); console.log(` Це файл: ${stats.isFile()}`); console.log(` Це каталог: ${stats.isDirectory()}`); console.log(` Розмір: ${stats.size} байт`); console.log(` Час створення: ${stats.birthtime.toISOString()}`); console.log(` Остання модифікація: ${stats.mtime.toISOString()}`); } catch (error: any) { console.error(`Помилка отримання статистики для '${path}' з промісами: ${error.message}`); } } getFileStats('data/example.txt'); getFileStats('data/non_existent_dir_or_file'); // Має повернути помилку

Операції з каталогами в TypeScript

Керування каталогами є поширеною вимогою для організації файлів, створення специфічного для додатку сховища або обробки тимчасових даних. TypeScript надає надійну типізацію для цих операцій.

Створення каталогів: `mkdir`, `mkdirSync`

Функція `fs.mkdir` використовується для створення нових каталогів. Опція `recursive` є надзвичайно корисною для створення батьківських каталогів, якщо вони ще не існують, імітуючи поведінку `mkdir -p` в Unix-подібних системах.

Асинхронне створення каталогу

import * as fs from 'fs'; const newDirPath: string = 'data/new_directory'; const recursiveDirPath: string = 'data/nested/path/to/create'; // Створення одного каталогу fs.mkdir(newDirPath, (err: NodeJS.ErrnoException | null) => { if (err) { // Ігноруємо помилку EEXIST, якщо каталог вже існує if (err.code === 'EEXIST') { console.log(`Каталог '${newDirPath}' вже існує.`); } else { console.error(`Помилка створення каталогу '${newDirPath}': ${err.message}`); } return; } console.log(`Каталог '${newDirPath}' успішно створено.`); }); // Рекурсивне створення вкладених каталогів fs.mkdir(recursiveDirPath, { recursive: true }, (err: NodeJS.ErrnoException | null) => { if (err) { if (err.code === 'EEXIST') { console.log(`Каталог '${recursiveDirPath}' вже існує.`); } else { console.error(`Помилка створення рекурсивного каталогу '${recursiveDirPath}': ${err.message}`); } return; } console.log(`Рекурсивні каталоги '${recursiveDirPath}' успішно створено.`); });

Створення каталогу на основі промісів (`fs/promises`)

import * as fsPromises from 'fs/promises'; async function createDirectory(path: string, recursive: boolean = false): Promise { try { await fsPromises.mkdir(path, { recursive: recursive }); console.log(`Каталог '${path}' успішно створено (рекурсивно: ${recursive}).`); } catch (error: any) { // Node.js викине помилку 'EEXIST', якщо recursive: false і каталог існує if (error.code === 'EEXIST' && !recursive) { console.log(`Каталог '${path}' вже існує.`); } else if (error.code === 'EEXIST' && recursive) { // З recursive: true, EEXIST не є помилкою, це просто означає, що він існує console.log(`Рекурсивний шлях '${path}' вже існує.`); } else { console.error(`Помилка створення каталогу '${path}' з промісами: ${error.message}`); } } } (async () => { await createDirectory('data/promise_dir'); await createDirectory('data/promise_dir'); // Демонстрація обробки EEXIST await createDirectory('data/promise_nested/path', true); })();

Читання вмісту каталогу: `readdir`, `readdirSync`, `fs.Dirent`

Для отримання списку файлів та підкаталогів у заданому каталозі використовується `fs.readdir`. Опція `withFileTypes` є сучасним доповненням, яке повертає об'єкти `fs.Dirent`, надаючи більш детальну інформацію безпосередньо, без необхідності викликати `stat` для кожного елемента окремо.

Асинхронне читання каталогу

import * as fs from 'fs'; const readDirPath: string = 'data'; fs.readdir(readDirPath, (err: NodeJS.ErrnoException | null, files: string[]) => { if (err) { console.error(`Помилка читання каталогу '${readDirPath}': ${err.message}`); return; } console.log(`Вміст каталогу '${readDirPath}':`); files.forEach(file => { console.log(` - ${file}`); }); }); // З опцією `withFileTypes` fs.readdir(readDirPath, { withFileTypes: true }, (err: NodeJS.ErrnoException | null, dirents: fs.Dirent[]) => { if (err) { console.error(`Помилка читання каталогу з типами файлів '${readDirPath}': ${err.message}`); return; } console.log(`Вміст каталогу '${readDirPath}' (з типами):`); dirents.forEach(dirent => { const type: string = dirent.isFile() ? 'Файл' : dirent.isDirectory() ? 'Каталог' : 'Інше'; console.log(` - ${dirent.name} (${type})`); }); });

Читання каталогу на основі промісів (`fs/promises`)

import * as fsPromises from 'fs/promises'; import { Dirent } from 'fs'; // Все ще використовуємо інтерфейс Dirent з модуля 'fs' async function listDirectoryContents(path: string): Promise { try { const files: string[] = await fsPromises.readdir(path); console.log(`Вміст каталогу '${path}' на основі промісів:`); files.forEach(file => console.log(` - ${file}`)); } catch (error: any) { console.error(`Помилка отримання списку каталогу '${path}' з промісами: ${error.message}`); } } async function listDirectoryContentsWithTypes(path: string): Promise { try { const dirents: Dirent[] = await fsPromises.readdir(path, { withFileTypes: true }); console.log(`Вміст каталогу '${path}' на основі промісів (з типами):`); dirents.forEach(dirent => { const type: string = dirent.isFile() ? 'Файл' : dirent.isDirectory() ? 'Каталог' : 'Інше'; console.log(` - ${dirent.name} (${type})`); }); } catch (error: any) { console.error(`Помилка отримання списку каталогу '${path}' з типами (проміси): ${error.message}`); } } (async () => { // Переконаємося, що каталог 'data' та деякі файли існують для демонстрації await fsPromises.mkdir('data', { recursive: true }); await fsPromises.writeFile('data/temp_file1.txt', 'Вміст 1'); await fsPromises.mkdir('data/sub_dir'); await fsPromises.writeFile('data/sub_dir/temp_file2.txt', 'Вміст 2'); await listDirectoryContents('data'); await listDirectoryContentsWithTypes('data'); await listDirectoryContents('non_existent_dir'); // Має повернути помилку })();

Видалення каталогів: `rmdir` (застарілий), `rm`, `rmSync`

Node.js розвинув свої методи видалення каталогів. `fs.rmdir` тепер значною мірою замінений на `fs.rm` для рекурсивних видалень, пропонуючи більш надійний та послідовний API.

Асинхронне видалення каталогу (`fs.rm`)

Функція `fs.rm` (доступна з Node.js 14.14.0) є рекомендованим способом видалення файлів та каталогів. Опція `recursive: true` є критично важливою для видалення непустих каталогів.

import * as fs from 'fs'; const dirToDeletePath: string = 'data/dir_to_delete'; const nestedDirToDeletePath: string = 'data/nested_dir/sub'; // Налаштування: Створюємо каталог з файлом всередині для демонстрації рекурсивного видалення fs.mkdir(nestedDirToDeletePath, { recursive: true }, (err) => { if (err && err.code !== 'EEXIST') { console.error('Помилка створення вкладеного каталогу для демонстрації:', err); return; } fs.writeFile(`${nestedDirToDeletePath}/file_inside.txt`, 'Деякий вміст', (err) => { if (err) { console.error('Помилка створення файлу всередині вкладеного каталогу:', err); return; } console.log(`Каталог '${nestedDirToDeletePath}' та файл створено для демонстрації видалення.`); fs.rm(nestedDirToDeletePath, { recursive: true, force: true }, (err: NodeJS.ErrnoException | null) => { if (err) { console.error(`Помилка видалення рекурсивного каталогу '${nestedDirToDeletePath}': ${err.message}`); return; } console.log(`Рекурсивний каталог '${nestedDirToDeletePath}' успішно видалено.`); }); }); }); // Видалення пустого каталогу fs.mkdir(dirToDeletePath, (err) => { if (err && err.code !== 'EEXIST') { console.error('Помилка створення пустого каталогу для демонстрації:', err); return; } console.log(`Каталог '${dirToDeletePath}' створено для демонстрації видалення.`); fs.rm(dirToDeletePath, { recursive: false }, (err: NodeJS.ErrnoException | null) => { if (err) { console.error(`Помилка видалення пустого каталогу '${dirToDeletePath}': ${err.message}`); return; } console.log(`Пустий каталог '${dirToDeletePath}' успішно видалено.`); }); });

Видалення каталогу на основі промісів (`fs/promises`)

import * as fsPromises from 'fs/promises'; async function deleteDirectory(path: string, recursive: boolean = false): Promise { try { // Створюємо фіктивну вкладену структуру для тестування рекурсивного видалення if (recursive) { await fsPromises.mkdir(`${path}/sub_dir`, { recursive: true }); await fsPromises.writeFile(`${path}/sub_dir/file.txt`, 'test'); } else { await fsPromises.mkdir(path, { recursive: true }); // Переконуємося, що батьківський каталог існує } console.log(`Налаштування каталогу в '${path}' для видалення.`); await fsPromises.rm(path, { recursive: recursive, force: true }); console.log(`Каталог '${path}' успішно видалено (рекурсивно: ${recursive}).`); } catch (error: any) { console.error(`Помилка видалення каталогу '${path}' з промісами: ${error.message}`); } } (async () => { await deleteDirectory('data/promise_dir_to_delete', false); // Видалити пустий await deleteDirectory('data/promise_nested_dir_to_delete', true); // Видалити непустий await deleteDirectory('data/non_existent_dir_to_delete'); // Має обробитись коректно })();

Розширені концепції файлової системи з TypeScript

Окрім базових операцій читання/запису, Node.js пропонує потужні функції для роботи з великими файлами, неперервними потоками даних та моніторингом файлової системи в реальному часі. Декларації типів TypeScript чудово розширюються на ці розширені сценарії, забезпечуючи надійність.

Файлові дескриптори та потоки

Для дуже великих файлів або коли потрібен детальний контроль над доступом до файлу (наприклад, конкретні позиції у файлі), файлові дескриптори та потоки стають незамінними. Потоки надають ефективний спосіб обробки читання або запису великих обсягів даних частинами, замість завантаження всього файлу в пам'ять, що є критично важливим для масштабованих додатків та ефективного управління ресурсами на серверах по всьому світу.

Відкриття та закриття файлів з дескрипторами (`fs.open`, `fs.close`)

Файловий дескриптор — це унікальний ідентифікатор (число), що присвоюється операційною системою відкритому файлу. Ви можете використовувати `fs.open`, щоб отримати файловий дескриптор, потім виконувати операції, такі як `fs.read` або `fs.write`, використовуючи цей дескриптор, і, нарешті, закрити його за допомогою `fs.close`.

import * as fs from 'fs'; import { promises as fsPromises } from 'fs'; import { constants } from 'fs'; const descriptorFilePath: string = 'data/descriptor_example.txt'; async function demonstrateFileDescriptorOperations(): Promise { let fileDescriptor: number | undefined; try { // Переконуємося, що файл існує для читання, або створюємо його для запису await fsPromises.writeFile(descriptorFilePath, 'Вміст для читання та модифікації через дескриптор.'); console.log(`Файл '${descriptorFilePath}' підготовлено для демонстрації дескриптора.`); // Відкриваємо файл для читання та запису (прапорець 'r+') // fsPromises.open повертає об'єкт FileHandle, який має власний дескриптор const fileHandle = await fsPromises.open(descriptorFilePath, constants.O_RDWR); // O_RDWR для читання та запису fileDescriptor = fileHandle.fd; // Отримуємо сирий файловий дескриптор console.log(`Файл відкрито з дескриптором: ${fileDescriptor}`); // Читаємо дані з файлу const buffer = Buffer.alloc(100); const { bytesRead, buffer: readBuffer } = await fileHandle.read(buffer, 0, buffer.length, 0); console.log(`Прочитано ${bytesRead} байт з дескриптора: '${readBuffer.toString('utf8', 0, bytesRead)}'`); // Записуємо дані в певну позицію (наприклад, перезаписуємо 'Вміст' на 'ОНОВЛЕНО') const writeData = Buffer.from('ОНОВЛЕНО'); const { bytesWritten } = await fileHandle.write(writeData, 0, writeData.length, 0); console.log(`Записано ${bytesWritten} байт в дескриптор.`); // Читаємо знову, щоб підтвердити зміни const bufferAfterWrite = Buffer.alloc(100); const { bytesRead: br2, buffer: readBuffer2 } = await fileHandle.read(bufferAfterWrite, 0, bufferAfterWrite.length, 0); console.log(`Вміст після запису: '${readBuffer2.toString('utf8', 0, br2)}'`); await fileHandle.close(); console.log('Файловий дескриптор закрито.'); } catch (error: any) { console.error(`Помилка з операціями файлового дескриптора: ${error.message}`); } finally { if (fileDescriptor !== undefined) { // Цей блок 'finally' обробляє випадки, коли помилка може виникнути *після* fileHandle.open, // але *до* виклику fileHandle.close, забезпечуючи очищення. // У цій конкретній структурі async/await, fileHandle.close() всередині try зазвичай достатньо, // якщо тільки сам fileHandle не зазнає невдачі до виклику .close(). } } } demonstrateFileDescriptorOperations();

Файлові потоки (`fs.createReadStream`, `fs.createWriteStream`)

Потоки є потужним інструментом для ефективної роботи з великими файлами. `fs.createReadStream` та `fs.createWriteStream` повертають потоки `Readable` та `Writable` відповідно, які безшовно інтегруються з потоковим API Node.js. TypeScript надає чудові визначення типів для подій цих потоків (наприклад, `'data'`, `'end'`, `'error'`).

import * as fs from 'fs'; const largeFilePath: string = 'data/large_file.txt'; const copiedFilePath: string = 'data/copied_file.txt'; // Створюємо фіктивний великий файл для демонстрації function createLargeFile(path: string, sizeInMB: number): void { const content: string = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. '; // 56 символів const stream = fs.createWriteStream(path); const totalChars = sizeInMB * 1024 * 1024; // Перетворюємо МБ в байти const iterations = Math.ceil(totalChars / content.length); for (let i = 0; i < iterations; i++) { stream.write(content); } stream.end(() => console.log(`Створено великий файл '${path}' (${sizeInMB}МБ).`)); } // Для демонстрації спочатку переконаємося, що каталог 'data' існує fs.mkdir('data', { recursive: true }, (err) => { if (err && err.code !== 'EEXIST') { console.error('Помилка створення каталогу data:', err); return; } createLargeFile(largeFilePath, 1); // Створюємо файл розміром 1 МБ }); // Копіювання файлу за допомогою потоків function copyFileWithStreams(source: string, destination: string): void { const readStream = fs.createReadStream(source); const writeStream = fs.createWriteStream(destination); readStream.on('open', () => console.log(`Потік для читання '${source}' відкрито.`)); writeStream.on('open', () => console.log(`Потік для запису '${destination}' відкрито.`)); // Перенаправляємо дані з потоку читання в потік запису readStream.pipe(writeStream); readStream.on('error', (err: Error) => { console.error(`Помилка потоку читання: ${err.message}`); }); writeStream.on('error', (err: Error) => { console.error(`Помилка потоку запису: ${err.message}`); }); writeStream.on('finish', () => { console.log(`Файл '${source}' успішно скопійовано в '${destination}' за допомогою потоків.`); // Видаляємо фіктивний великий файл після копіювання fs.unlink(largeFilePath, (err) => { if (err) console.error('Помилка видалення великого файлу:', err); else console.log(`Великий файл '${largeFilePath}' видалено.`); }); }); } // Чекаємо трохи, поки великий файл створиться, перед спробою копіювання setTimeout(() => { copyFileWithStreams(largeFilePath, copiedFilePath); }, 1000);

Спостереження за змінами: `fs.watch`, `fs.watchFile`

Моніторинг файлової системи на предмет змін є життєво важливим для таких завдань, як гаряче перезавантаження серверів розробки, процеси збірки або синхронізація даних у реальному часі. Node.js надає два основні методи для цього: `fs.watch` та `fs.watchFile`. TypeScript забезпечує коректну обробку типів подій та параметрів слухачів.

`fs.watch`: Спостереження за файловою системою на основі подій

`fs.watch` зазвичай є більш ефективним, оскільки він часто використовує сповіщення на рівні операційної системи (наприклад, `inotify` на Linux, `kqueue` на macOS, `ReadDirectoryChangesW` на Windows). Він підходить для моніторингу конкретних файлів або каталогів на предмет змін, видалень або перейменувань.

import * as fs from 'fs'; const watchedFilePath: string = 'data/watched_file.txt'; const watchedDirPath: string = 'data/watched_dir'; // Переконуємося, що файли/каталоги існують для спостереження fs.writeFileSync(watchedFilePath, 'Початковий вміст.'); fs.mkdirSync(watchedDirPath, { recursive: true }); console.log(`Спостерігаємо за змінами в '${watchedFilePath}'...`); const fileWatcher = fs.watch(watchedFilePath, (eventType: string, filename: string | Buffer | null) => { const fname = typeof filename === 'string' ? filename : filename?.toString('utf8'); console.log(`Подія файлу '${fname || 'N/A'}': ${eventType}`); if (eventType === 'change') { console.log('Вміст файлу, можливо, змінився.'); } // У реальному додатку ви могли б тут прочитати файл або запустити перебудову }); console.log(`Спостерігаємо за змінами в каталозі '${watchedDirPath}'...`); const dirWatcher = fs.watch(watchedDirPath, (eventType: string, filename: string | Buffer | null) => { const fname = typeof filename === 'string' ? filename : filename?.toString('utf8'); console.log(`Подія каталогу '${watchedDirPath}': ${eventType} на '${fname || 'N/A'}'`); }); fileWatcher.on('error', (err: Error) => console.error(`Помилка спостерігача файлу: ${err.message}`)); dirWatcher.on('error', (err: Error) => console.error(`Помилка спостерігача каталогу: ${err.message}`)); // Симулюємо зміни після затримки setTimeout(() => { console.log('\n--- Симуляція змін ---'); fs.appendFileSync(watchedFilePath, '\nДодано новий рядок.'); fs.writeFileSync(`${watchedDirPath}/new_file.txt`, 'Вміст.'); fs.unlinkSync(`${watchedDirPath}/new_file.txt`); // Також тестуємо видалення setTimeout(() => { fileWatcher.close(); dirWatcher.close(); console.log('\nСпостерігачі закрито.'); // Очищаємо тимчасові файли/каталоги fs.unlinkSync(watchedFilePath); fs.rmSync(watchedDirPath, { recursive: true, force: true }); }, 2000); }, 1000);

Примітка щодо `fs.watch`: Він не завжди надійний на всіх платформах для всіх типів подій (наприклад, перейменування файлів може повідомлятися як видалення та створення). Для надійного міжплатформенного спостереження за файлами розгляньте бібліотеки, такі як `chokidar`, які часто використовують `fs.watch` під капотом, але додають нормалізацію та резервні механізми.

`fs.watchFile`: Спостереження за файлами на основі опитування

`fs.watchFile` використовує опитування (періодичну перевірку `stat` даних файлу) для виявлення змін. Це менш ефективно, але більш послідовно на різних файлових системах та мережевих дисках. Це краще підходить для середовищ, де `fs.watch` може бути ненадійним (наприклад, NFS-ресурси).

import * as fs from 'fs'; import { Stats } from 'fs'; const pollFilePath: string = 'data/polled_file.txt'; fs.writeFileSync(pollFilePath, 'Початковий вміст для опитування.'); console.log(`Опитуємо '${pollFilePath}' на предмет змін...`); fs.watchFile(pollFilePath, { interval: 1000 }, (curr: Stats, prev: Stats) => { // TypeScript гарантує, що 'curr' та 'prev' є об'єктами fs.Stats if (curr.mtimeMs !== prev.mtimeMs) { console.log(`Файл '${pollFilePath}' змінено (змінився mtime). Новий розмір: ${curr.size} байт.`); } }); setTimeout(() => { console.log('\n--- Симуляція зміни файлу, що опитується ---'); fs.appendFileSync(pollFilePath, '\nДодано ще один рядок до файлу.'); setTimeout(() => { fs.unwatchFile(pollFilePath); console.log(`\nПрипинено спостереження за '${pollFilePath}'.`); fs.unlinkSync(pollFilePath); }, 2000); }, 1500);

Обробка помилок та найкращі практики в глобальному контексті

Надійна обробка помилок є першочерговою для будь-якого готового до виробництва додатку, особливо того, що взаємодіє з файловою системою. Файлові операції можуть зазнати невдачі з численних причин: проблеми з дозволами, заповнений диск, файл не знайдено, помилки вводу-виводу, проблеми з мережею (для мережевих дисків) або конфлікти одночасного доступу. TypeScript допомагає виявляти проблеми, пов'язані з типами, але помилки часу виконання все ще потребують ретельного управління.

Стратегії обробки помилок

• Синхронні операції: Завжди обгортайте виклики `fs.xxxSync` у блоки `try...catch`. Ці методи безпосередньо викидають помилки.
• Асинхронні колбеки: Першим аргументом колбеку `fs` завжди є `err: NodeJS.ErrnoException | null`. Завжди перевіряйте цей об'єкт `err` в першу чергу.
• На основі промісів (`fs/promises`): Використовуйте `try...catch` з `await` або `.catch()` з ланцюжками `.then()` для обробки відхилень.

Корисно стандартизувати формати логування помилок та враховувати інтернаціоналізацію (i18n) для повідомлень про помилки, якщо зворотний зв'язок про помилки вашого додатку призначений для користувача.

import * as fs from 'fs'; import { promises as fsPromises } from 'fs'; import * as path from 'path'; const problematicPath = path.join('non_existent_dir', 'file.txt'); // Синхронна обробка помилок try { fs.readFileSync(problematicPath, 'utf8'); } catch (error: any) { console.error(`Синхронна помилка: ${error.code} - ${error.message} (Шлях: ${problematicPath})`); } // Обробка помилок на основі колбеків fs.readFile(problematicPath, 'utf8', (err, data) => { if (err) { console.error(`Помилка колбеку: ${err.code} - ${err.message} (Шлях: ${problematicPath})`); return; } // ... обробка даних }); // Обробка помилок на основі промісів async function safeReadFile(filePath: string): Promise { try { return await fsPromises.readFile(filePath, 'utf8'); } catch (error: any) { console.error(`Помилка промісу: ${error.code} - ${error.message} (Шлях: ${filePath})`); return null; } } safeReadFile(problematicPath).then(content => { if (content !== null) { // ... обробка вмісту } });

Управління ресурсами: Закриття файлових дескрипторів

При роботі з `fs.open` (або `fsPromises.open`) критично важливо забезпечити, щоб файлові дескриптори завжди закривалися за допомогою `fs.close` (або `fileHandle.close()`) після завершення операцій, навіть якщо виникають помилки. Недотримання цього може призвести до витоку ресурсів, досягнення ліміту відкритих файлів операційної системи та потенційно до збою вашого додатку або впливу на інші процеси.

API `fs/promises` з об'єктами `FileHandle` загалом спрощує це, оскільки `fileHandle.close()` спеціально розроблений для цієї мети, а екземпляри `FileHandle` є `Disposable` (якщо використовується Node.js 18.11.0+ та TypeScript 5.2+).

Управління шляхами та міжплатформенна сумісність

Шляхи до файлів значно відрізняються між операційними системами (наприклад, `\` на Windows, `/` на Unix-подібних системах). Модуль `path` у Node.js є незамінним для створення та аналізу шляхів до файлів у спосіб, сумісний з різними платформами, що є необхідним для глобальних розгортань.

• `path.join(...paths)`: Об'єднує всі задані сегменти шляху, нормалізуючи отриманий шлях.
• `path.resolve(...paths)`: Перетворює послідовність шляхів або сегментів шляху на абсолютний шлях.
• `path.basename(path)`: Повертає останню частину шляху.
• `path.dirname(path)`: Повертає назву каталогу шляху.
• `path.extname(path)`: Повертає розширення шляху.

TypeScript надає повні визначення типів для модуля `path`, забезпечуючи правильне використання його функцій.

import * as path from 'path'; const dir = 'my_app_data'; const filename = 'config.json'; // Міжплатформенне об'єднання шляхів const fullPath: string = path.join(__dirname, dir, filename); console.log(`Міжплатформенний шлях: ${fullPath}`); // Отримання назви каталогу const dirname: string = path.dirname(fullPath); console.log(`Назва каталогу: ${dirname}`); // Отримання базової назви файлу const basename: string = path.basename(fullPath); console.log(`Базова назва: ${basename}`); // Отримання розширення файлу const extname: string = path.extname(fullPath); console.log(`Розширення: ${extname}`);

Паралелізм та стани гонитви

Коли кілька асинхронних файлових операцій ініціюються одночасно, особливо записи або видалення, можуть виникати стани гонитви. Наприклад, якщо одна операція перевіряє існування файлу, а інша видаляє його до того, як перша операція виконає свою дію, перша операція може несподівано зазнати невдачі.

• Уникайте `fs.existsSync` для критичної логіки; надавайте перевагу `fs.access` або просто спробуйте виконати операцію та обробіть помилку.
• Для операцій, що вимагають ексклюзивного доступу, використовуйте відповідні опції `flag` (наприклад, `'wx'` для ексклюзивного запису).
• Впроваджуйте механізми блокування (наприклад, файлові блокування або блокування на рівні додатку) для доступу до критично важливих спільних ресурсів, хоча це додає складності.

Дозволи (ACL)

Дозволи файлової системи (Списки контролю доступу або стандартні дозволи Unix) є поширеним джерелом помилок. Переконайтеся, що ваш процес Node.js має необхідні дозволи для читання, запису або виконання файлів та каталогів. Це особливо актуально в контейнеризованих середовищах або на багатокористувацьких системах, де процеси виконуються під певними обліковими записами користувачів.

Висновок: Використання безпеки типів для глобальних операцій з файловою системою

Модуль `fs` у Node.js — це потужний та універсальний інструмент для взаємодії з файловою системою, що пропонує спектр можливостей від базових маніпуляцій з файлами до розширеної обробки даних на основі потоків. Накладаючи TypeScript на ці операції, ви отримуєте неоціненні переваги: виявлення помилок на етапі компіляції, покращену зрозумілість коду, чудову підтримку інструментів та підвищену впевненість під час рефакторингу. Це особливо важливо для глобальних команд розробників, де послідовність та зменшення неоднозначності в різноманітних кодових базах є життєво важливими.

Незалежно від того, чи ви створюєте невеликий утилітарний скрипт, чи великомасштабний корпоративний додаток, використання надійної системи типів TypeScript для ваших операцій з файлами в Node.js призведе до більш підтримуваного, надійного та стійкого до помилок коду. Використовуйте API `fs/promises` для чистіших асинхронних патернів, розумійте нюанси між синхронними та асинхронними викликами, і завжди надавайте пріоритет надійній обробці помилок та міжплатформенному управлінню шляхами.

Застосовуючи принципи та приклади, обговорені в цьому посібнику, розробники по всьому світу можуть створювати взаємодії з файловою системою, які є не тільки продуктивними та ефективними, але й за своєю суттю більш безпечними та легшими для розуміння, що в кінцевому підсумку сприяє вищій якості програмних продуктів.